Node / styrene-lab / omegon-armory.git / files / docs / compatibility.md

Displaying Rendered • View raw • Download

Armory is the public package registry for Omegon-native agentic additions, but its artifact shapes intentionally overlap with broader agent ecosystems: prompt packs, agent cards, MCP servers, CLI tools, tool manifests, and project instruction files.

The compatibility goal is full fidelity in Omegon, graceful degradation everywhere else.

Omegon remains the native runtime. Other agent hosts should still be able to consume Armory packages as useful prompts, manifests, tool descriptors, or dependency recommendations without implementing the full Omegon environment.

An Armory package has three layers:

1. Payload — markdown, TOML, JSON, archives, source pointers, or native extension artifacts.

2. Metadata — package kind, id, version, description, capabilities, dependencies, digest, and source.

3. Compatibility contract — how the package behaves in Omegon and what it degrades to elsewhere.

The compatibility contract should be explicit and machine-readable. Consumers should not have to infer whether a package is a prompt, tool, profile, agent blueprint, or native-only extension.

Every public Armory package should support tier 0. Most text packages should support tier 1. Profiles and agents should support tier 2. Extensions should aim for tier 3 where possible.

A consumer should use the highest supported level and fall back safely:

T282828

A failed high-fidelity install should not make the package useless. It should expose the lower-fidelity path.

Skills are the most portable Armory package.

Native behavior:

T282828

Degraded behavior:

• read guidance markdown;

• inject as project instructions;

• convert to host-specific rule files;

• use as checklist or review policy.

Portable entrypoints:

T282828

Target compatibility metadata:

T282828

Personas are also highly portable.

Native behavior:

T282828

Degraded behavior:

• system prompt;

• role prompt;

• assistant card;

• optional memory seed where supported.

Portable entrypoints:

T282828

Degradation rules:

• if memory is unsupported, ignore T383838mind/facts.jsonl;

• if tool policy is unsupported, treat it as advisory text;

• if persona metadata is unsupported, use T383838PERSONA.md only.

Tones should remain style-only and avoid policy/tool semantics.

Native behavior:

T282828

Degraded behavior:

• writing style instruction;

• response formatting guide;

• tone preamble.

Portable entrypoints:

T282828

Forge templates are Nex-owned Pkl payloads distributed by Armory. They are not Omegon profiles and must not be interpreted as agent environment configuration.

Native behavior:

T282828

Degraded behavior:

• inspect T383838forge.toml, T383838forge.pkl, and T383838README.md;

• use metadata such as T383838canonicalFormat, T383838minNex, T383838destructiveCapabilities, and T383838networkRequirements;

• do not execute or flash anything from Armory. Nex owns evaluation and destructive-operation controls.

Profiles are Armory meta-packages. They reference dependencies instead of copying them.

Native behavior:

T282828

Degraded behavior:

• dependency manifest;

• recommended stack;

• source for generated T383838AGENTS.md, T383838CLAUDE.md, Cursor rules, or similar project files.

Portable entrypoints:

T282828

Profile dependency metadata should be sufficient to answer:

• which dependencies are required?

• which are optional?

• which should activate automatically?

• which require native Omegon extension support?

• which can be rendered as prompt material elsewhere?

Example external transform:

T282828

Catalog agents are native Omegon bundles, but their contents should include a portable subset.

Native behavior:

T282828

Degraded behavior:

• assistant blueprint;

• prompt + settings recipe;

• memory seed;

• tool requirement list;

• runbook automation template.

Portable entrypoints:

T282828

The portable T383838agent.toml subset should be documented separately from the native T383838agent.pkl representation.

Extensions are the hard edge because they may expose native tools, background services, UI surfaces, browser integrations, or model pipelines.

Native behavior:

T282828

Degraded behavior:

1. MCP interface if declared.

2. CLI interface if declared.

3. HTTP/OpenAPI interface if declared.

4. Manual external tool reference if no callable interface exists.

Target extension interface metadata:

T282828

A non-Omegon host should never assume an extension is callable just because it exists in Armory. It should inspect declared interfaces.

The public API should eventually add a T383838compatibility object to each item.

Initial generated shape:

T282828

Kind-specific default generation is acceptable for the first implementation. Source manifests can grow explicit overrides later.

Armory should not deeply couple to every agent host, but common export targets are useful.

A future T383838armory export command can implement these transforms without changing package payloads.

Armory can also normalize external ecosystems.

The import rule: preserve the original artifact where useful, but declare the portable Armory kind and compatibility tier explicitly.

Compatibility increases redistribution. Treat all public Armory payloads as world-readable.

Public packages must not contain:

• raw secrets;

• private hostnames that reveal sensitive topology;

• internal IP addresses;

• private incident details;

• home-lab or production operational specifics not intended for publication;

• credentials by value;

• environment-specific memory facts unless intentionally public.

Private or organization-specific packages belong in a private/federated Armory, not the public Styrene Armory.

T383838mind/facts.jsonl, T383838PERSONA.md, T383838agent.toml, T383838profile.toml, and extension manifests need the same review standard as source code.

• Publish this compatibility model.

• Add generated T383838compatibility metadata to T383838site/public/api/index.json and T383838site/src/data/armory.json.

• Generate conservative defaults by package kind.

• Add tests that every public item has compatibility metadata.

• Keep source manifests unchanged unless an override is needed.

Acceptance criteria:

• API consumers can tell how to use each package outside Omegon.

• Existing site build remains static and generated from manifests.

• No package loses native Omegon install metadata.

• Add T383838[interfaces.omegon] to every enabled extension detail file.

• Add T383838[interfaces.mcp], T383838[interfaces.cli], and T383838[interfaces.http] sections where known.

• Treat undeclared portable tool interfaces as unsupported.

• Render interface support on extension pages.

Acceptance criteria:

• Non-Omegon hosts can distinguish callable extensions from documentation-only extensions.

• MCP bridge candidates are visible without implying support that does not exist.

• Add an T383838armory export design/API for transforming packages into host-specific files.

• Start with no-runtime transforms:

• T383838generic-markdown

• T383838agents-md

• T383838claude-md

• T383838cursor-rules

• Profiles should resolve dependency graphs and render required prompt-compatible dependencies.

• Extensions without portable interfaces should render as setup notes only.

Acceptance criteria:

• A non-Omegon user can export T383838python-shop into useful project instructions.

• Optional/native-only dependencies are clearly marked, not silently dropped.

• Define import conventions for MCP servers, CLI tools, prompt packs, and agent cards.

• Add validation for imported package metadata.

• Consider private/federated Armory workflows for organization-specific imports.

Acceptance criteria:

• Armory can represent external agentic additions without pretending they are Omegon-native.

• Native support and degraded support are explicit.

• Add fixture tests for each kind.

• Verify all package pages and API records expose compatibility data.

• Verify profile dependencies map to compatibility entries.

• Verify extension interface sections do not overclaim support.

• Add secret/topology linting for portable payloads.

Acceptance criteria:

• Publication fails if a package lacks compatibility metadata.

• Publication fails if public payloads contain obvious private operational material.

• Omegon is the full-fidelity runtime, not the only consumer.

• Degradation is a first-class feature, not an accidental side effect.

• Profiles reference dependencies; they do not copy dependency payloads.

• Extensions must declare portable interfaces before other hosts treat them as callable tools.

• Public Armory is for generally reusable packages. Private operational agents belong in private/federated Armory.